Add async worker execution mode by crmne · Pull Request #728 · rails/solid_queue

crmne · 2026-04-04T14:02:58Z

Summary

Hi @rosa, I finally had some time to work on this after our earlier conversation about async worker execution mode.

This PR is a first implementation of async worker execution mode for Solid Queue. I'm also running benchmarks in parallel and can follow up with numbers once I have stable results.

Workers can now be configured with execution_mode: :async (or :fiber), which runs claimed jobs as fibers on a single async reactor thread and bounds concurrency with capacity / fibers instead of a thread pool.

This is separate from supervisor async mode. Supervisor mode still controls whether managed processes run in forks or threads; this change adds an async execution backend for workers themselves.

What Changed

added an execution pool abstraction for workers
introduced SolidQueue::ExecutionPools::AsyncPool
moved existing thread-pool behavior into SolidQueue::ExecutionPools::ThreadPool
added execution_mode: :async and :fiber as a configuration alias
added capacity / fibers as the clearer async-worker concurrency options
updated workers to build execution pools after fork/boot rather than during initialize
updated worker metadata to report execution mode, capacity, and inflight work across both backends
wake workers when capacity becomes available again so async execution integrates cleanly with the poll loop
treat async pool cancellation as fatal so reactor failures are surfaced instead of being silently ignored

Configuration / Validation

This PR also tightens async worker validation:

async workers require fiber-scoped isolated execution state
async workers fail early if the async gem is not available
async workers reject threads: and require capacity or fibers instead

Database pool guidance is now Rails-version-aware:

Rails 7.1 keeps the conservative async DB-pool validation
Rails 7.2+ uses the lower async-worker bound, since ordinary Active Record query paths can release connections between async waits

The README now documents the version-specific DB-pool guidance and calls out sticky Active Record APIs that can still pin connections.

Why

The goal is to support cooperative, mostly I/O-bound job execution with lower thread overhead and a clearer concurrency model, while keeping the feature explicit and safe to configure.

Tests

Added and updated coverage for:

async pool behavior
async worker execution
worker metadata and wake-up behavior
async boot/shutdown/error handling
configuration validation
DB-pool validation and docs around Rails version differences

seanharmer · 2026-04-04T14:30:16Z

I've pushed my initial implementation for this to #729 for comparison. Feel free to take anything you deem useful. :)

crmne · 2026-04-05T18:20:20Z

Hi @rosa, I've published a benchmark harness that answers three questions:

Within Solid Queue: how much do I/O-heavy workloads benefit from async execution compared to thread mode?
DB pool ceiling: at what concurrency does thread mode exhaust the database connection pool, and how much further does async go?
Across backends: how does Solid Queue compare to Async::Job + Redis when both run through ActiveJob?

https://github.com/crmne/solid_queue_bench

Solid Queue: async vs thread

async wins the majority of headline tests. Strongest gains by workload:

Workload	Best delta	Win rate
`sleep`	+27.2%	6/9
`async_http`	+26.0%	5/9
`cpu`	+5.1%	7/9
`ruby_llm_stream`	+20.2%	9/9

The cleanest result is ruby_llm_stream (real RubyLLM streaming + Turbo broadcasts) -- async wins every test. cpu staying roughly neutral is the expected control, which makes the I/O gains credible.

DB pool ceiling (stress suite)

The headline suite caps total concurrency to keep comparisons fair. The stress suite removes that cap. thread mode hit the DB pool wall after the baseline cap=25, proc=2 test and failed every higher-concurrency cell. async completed all 10/10 planned tests per workload -- it multiplexes fibers over a much smaller connection pool, so it survives where threads cannot.

Async::Job vs Solid Queue

Async::Job + Redis is faster across all shared tests (+7% to +213%), but that's a different backend entirely -- a throughput ceiling reference, not a same-backend comparison.

Bottom line

The main async win is not raw throughput. It's good I/O performance without thread-sized DB pools and the connection pressure that comes with them. Under stress, that difference becomes binary: threads fail, fibers keep going.

crmne · 2026-04-07T16:30:26Z

I'm running this code in production at Chat with Work right now. Switched from Async::Job largely because of operational advantages, especially visibility from Mission Control Jobs when debugging failures.

bradgessler · 2026-04-09T15:36:37Z

Also running this in production and can confirm it works very well.

trevorturk · 2026-04-09T19:04:21Z

I wanted to highlight something to make sure it's more visible to others... it looks like this setup would allow for separately configured worker pools, so one could imagine putting "mostly waiting on LLMs or slow APIs" jobs into an async pool, and the "regular" work could be left on a thread pool. For example, in the PR changes here, you can see a config example like so:

- queues: "llm*"
  execution_mode: async
- queues: [ real_time, background ]
  execution_mode: thread

crmne added 7 commits April 2, 2026 11:29

Add async worker execution pools

e721253

Relax async worker connection pool validation

191883e

Handle async pool cancellations as fatal

444091d

Build worker pools after fork

ae0efbd

Gate async workers on fiber isolation

abbbbb4

Fail fast for async worker config errors

74e443e

Make async DB pool guidance Rails-version aware

a0e9444

This was referenced Apr 4, 2026

Support for async streaming in Solid Queue for AI response handling #596

Closed

How to make solid_queue work well with fibers? #150

Closed

Optimizing for used Connections #627

Open

Fix worker pool defaults and async shutdown

cac54bf

seanharmer mentioned this pull request Apr 4, 2026

Introduce async fiber-based worker mode for IO-bound jobs #729

Open

crmne added 6 commits April 4, 2026 16:38

Fix async pool compatibility and plugin tests

9ee9f75

Fix async pool compatibility on Ruby 3.1

92a9ccf

Add Ruby 3.1 async IO timeout compatibility

c6fca18

Harden async shutdown lifecycle test

302fc68

Stabilize concurrency controls assertions

98d13dc

Relax async lifecycle start wait

305bf40

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add async worker execution mode#728

Add async worker execution mode#728
crmne wants to merge 14 commits intorails:mainfrom
crmne:async-worker-execution-mode

crmne commented Apr 4, 2026 •

edited

Loading

Uh oh!

seanharmer commented Apr 4, 2026

Uh oh!

crmne commented Apr 5, 2026

Uh oh!

crmne commented Apr 7, 2026

Uh oh!

bradgessler commented Apr 9, 2026

Uh oh!

trevorturk commented Apr 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

crmne commented Apr 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What Changed

Configuration / Validation

Why

Tests

Uh oh!

seanharmer commented Apr 4, 2026

Uh oh!

crmne commented Apr 5, 2026

Solid Queue: async vs thread

DB pool ceiling (stress suite)

Async::Job vs Solid Queue

Bottom line

Uh oh!

crmne commented Apr 7, 2026

Uh oh!

bradgessler commented Apr 9, 2026

Uh oh!

trevorturk commented Apr 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

crmne commented Apr 4, 2026 •

edited

Loading